package org.example.springboot.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.annotation.Resource;
import org.example.springboot.common.Result;
import org.example.springboot.entity.OutstockApply;
import org.example.springboot.service.OutstockApplyService;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.*;

import java.util.List;
//Swagger 注解，为该控制器设置标签名称为“出库申请接口”。
@Tag(name = "出库申请接口")
//Spring 注解，表示该类是一个控制器，并且返回值直接写入 HTTP 响应体（用于构建 RESTful API）
@RestController
//基础请求路径为 /outstock。
@RequestMapping("/outstock")
public class OutstockApplyController {
    //使用 SLF4J 创建日志记录器实例，用于记录日志信息。
    // 注入 OutstockApplyService 实例，用于调用业务逻辑层方法。
    private static final Logger LOGGER = LoggerFactory.getLogger(OutstockApplyController.class);


    @Resource
    private OutstockApplyService outstockApplyService;
/*
* 功能：创建一个新的出库申请记录。
参数：
apply：封装了出库申请信息的对象（包含申请人 ID、商品 ID、数量、申请类型、原因等字段）。
流程：
调用 outstockApplyService.createApply(apply) 插入新申请数据。
返回值：
成功：Result.success(createdApply) 返回创建的申请对象。
失败：Result.error("-1", "创建失败") 或具体提示（如“库存不足”、“用户不存在”）。
* */
    @Operation(summary = "创建出库申请")
    //处理 POST 请求，路径为 /outstock。
    @PostMapping
    //@RequestBody OutstockApply apply：接收客户端传入的 JSON 数据并反序列化为 OutstockApply 对象。
    public Result<?> createApply(@RequestBody OutstockApply apply) {
        return outstockApplyService.createApply(apply);
    }
/*
* 功能：更新指定 ID 的出库申请信息。
参数：
id：出库申请记录 ID（路径变量）
apply：新的出库申请信息
流程：
设置申请 ID。
调用 outstockApplyService.updateApply(id, apply) 更新数据库记录。
返回值：
成功：Result.success(apply)
失败：Result.error("-1", "更新失败") 或具体原因（如“申请已审批无法修改”）
* */
    @Operation(summary = "更新出库申请")
    //@PutMapping("/{id}")：处理 PUT 请求，路径为 /outstock/{id}
    @PutMapping("/{id}")
    //@PathVariable Long id：获取 URL 中的 id 参数。
    //@RequestBody OutstockApply apply：接收更新数据。
    //return outstockApplyService.updateApply(id, apply);：调用服务层更新指定 ID 的出库申请。
    public Result<?> updateApply(@PathVariable Long id, @RequestBody OutstockApply apply) {
        return outstockApplyService.updateApply(id, apply);
    }
/*
* URL 示例：PUT /outstock/1001/approve?approvalStatus=1&approvalComment=同意&approverId=1002
功能：对指定 ID 的出库申请进行审批操作。
参数：
id：出库申请 ID（路径变量）
approvalStatus：审批状态（如 0: 待审批, 1: 已通过, 2: 驳回）
approvalComment：审批意见（可为空）
approverId：审批人 ID
流程：
调用 outstockApplyService.approveApply(...) 执行审批逻辑。
包括更新状态、记录审批人、更新库存等。
返回值：
成功：Result.success()
失败：Result.error("-1", "审批失败") 或具体原因（如“库存不足”、“状态非法”）
* */
    @Operation(summary = "审批出库申请")
    //处理 PUT 请求，路径为 /outstock/{id}/approve。
    @PutMapping("/{id}/approve")
    //@PathVariable Long id：获取 id。
    //@RequestParam Integer approvalStatus：接收审批状态参数。
    //@RequestParam Long approverId：接收审批人 ID。
    public Result<?> approveApply(@PathVariable Long id, @RequestParam Integer approvalStatus, @RequestParam String approvalComment, @RequestParam Long approverId) {
       //调用服务层进行审批操作。
        return outstockApplyService.approveApply(id, approvalStatus, approvalComment, approverId);
    }
/*
* URL 示例：GET /outstock/1001
功能：根据出库申请 ID 查询详情。
参数：
id：出库申请记录 ID（路径变量）
流程：
调用 outstockApplyService.getApplyById(id) 获取申请实体。
返回值：
成功：Result.success(apply)
失败：Result.error("-1", "未找到申请")
 * */
    @Operation(summary = "获取出库申请详情")
    //处理 GET 请求，路径为 /outstock/{id}。
    @GetMapping("/{id}")
    //@PathVariable Long id：获取 URL 中的 id 参数。
    //return outstockApplyService.getApplyById(id);：调用服务层方法获取指定 id 的出库申请详情。
    public Result<?> getApplyById(@PathVariable Long id) {
        return outstockApplyService.getApplyById(id);
    }
/*
* URL 示例：GET /outstock/page?applyType=0&status=1&applicantId=1001&currentPage=1&pageSize=10
功能：分页查询出库申请记录，支持按申请类型、状态、申请人筛选。
参数：
applyType：申请类型（如 0: 出库, 1: 退货）（可为空）
status：申请状态（如 0: 待审批, 1: 已通过, 2: 已驳回）（可为空）
applicantId：申请人 ID（可为空）
currentPage：当前页码（默认第一页）
pageSize：每页数量（默认 10 条）
流程：
构建查询条件并调用 outstockApplyService.getApplysByPage(...) 获取分页数据。
返回值：
成功：Result.success(page)，返回分页对象。
失败：Result.error("-1", "查询失败: ${message}")
* */
    @Operation(summary = "分页查询出库申请")
    //处理 GET 请求，路径为 /outstock/page。
    @GetMapping("/page")
/*
* */
    public Result<?> getApplysByPage(
            @RequestParam(required = false) Integer applyType, //筛选特定类型的出库申请。
            @RequestParam(required = false) Integer status,//筛选特定状态的申请。
            @RequestParam(required = false) Long applicantId,//筛选特定申请者的申请。
            @RequestParam(defaultValue = "1") Integer currentPage,//当前页码，默认为 1。
            @RequestParam(defaultValue = "10") Integer pageSize) {//每页显示的记录数，默认为 10。
        //调用服务层实现分页查询。
        return outstockApplyService.getApplysByPage(applyType, status, applicantId, currentPage, pageSize);
    }
/*
* URL 示例：DELETE /outstock/1001
功能：根据出库申请 ID 删除申请记录。
参数：
id：出库申请记录 ID（路径变量）
流程：
调用 outstockApplyService.deleteApply(id) 执行删除操作。
返回值：
成功：Result.success()
失败：Result.error("-1", "删除失败")
* */
    @Operation(summary = "删除出库申请")
    //处理 DELETE 请求，路径为 /outstock/{id}。
    @DeleteMapping("/{id}")
    //@PathVariable Long id：获取 id。
    //return outstockApplyService.deleteApply(id);：调用服务层删除指定 ID 的出库申请。
    public Result<?> deleteApply(@PathVariable Long id) {
        return outstockApplyService.deleteApply(id);
    }
/*
* URL 示例：DELETE /outstock/batch，请求体为 JSON：[1001, 1002, 1003]
功能：批量删除多个出库申请记录。
参数：
ids：出库申请 ID 列表（JSON 数组形式）
流程：
调用 outstockApplyService.deleteBatch(ids) 批量删除申请记录。
返回值：
成功：Result.success()
失败：Result.error("-1", "批量删除失败")
 * */
    @Operation(summary = "批量删除出库申请")
    //处理 DELETE 请求，路径为 /outstock/batch。
    @DeleteMapping("/batch")
    //@RequestBody List<Long> ids：接收要删除的多个 id 组成的列表。
    //return outstockApplyService.deleteBatch(ids);：调用服务层批量删除出库申请。
    public Result<?> deleteBatch(@RequestBody List<Long> ids) {
        return outstockApplyService.deleteBatch(ids);
    }
} 